<!-------- @HEADER
 !
 ! !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
 !
 !  Zoltan Toolkit for Load-balancing, Partitioning, Ordering and Coloring
 !                  Copyright 2012 Sandia Corporation
 !
 ! Under the terms of Contract DE-AC04-94AL85000 with Sandia Corporation,
 ! the U.S. Government retains certain rights in this software.
 !
 ! Redistribution and use in source and binary forms, with or without
 ! modification, are permitted provided that the following conditions are
 ! met:
 !
 ! 1. Redistributions of source code must retain the above copyright
 ! notice, this list of conditions and the following disclaimer.
 !
 ! 2. Redistributions in binary form must reproduce the above copyright
 ! notice, this list of conditions and the following disclaimer in the
 ! documentation and/or other materials provided with the distribution.
 !
 ! 3. Neither the name of the Corporation nor the names of the
 ! contributors may be used to endorse or promote products derived from
 ! this software without specific prior written permission.
 !
 ! THIS SOFTWARE IS PROVIDED BY SANDIA CORPORATION "AS IS" AND ANY
 ! EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
 ! IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
 ! PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL SANDIA CORPORATION OR THE
 ! CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
 ! EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
 ! PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
 ! PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
 ! LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
 ! NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
 ! SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 !
 ! Questions? Contact Karen Devine	kddevin@sandia.gov
 !                    Erik Boman	egboman@sandia.gov
 !
 ! !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
 !
 ! @HEADER
-------> 
<!doctype html public "-//w3c//dtd html 4.0 transitional//en">
<html>
<head>
   <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
   <meta name="GENERATOR" content="Mozilla/4.7 [en] (X11; U; SunOS 5.7 sun4u) [Netscape]">
   <meta name="sandia.approved" content="SAND99-1376">
   <meta name="author" content="william mitchell, william.mitchell@nist.gov">
   <title> Zoltan Developer's Guide:  Refinement Tree</title>

</head>
<body bgcolor="#FFFFFF">

<div ALIGN=right><b><i><a href="dev.html">Zoltan Developer's Guide</a>&nbsp;
|&nbsp; <a href="dev_hsfc.html">Next</a> &nbsp;
|&nbsp; <a href="dev_phg.html">Previous</a></i></b></div>


<h2>
Appendix: Refinement Tree</h2>

<h3>
Overview of structure (algorithm)</h3>
The refinement tree based partitioning algorithm was developed and implemented
by <a href="https://math.nist.gov/~mitchell">William Mitchell</a> of the National Institute of Standards and Technology.
It is similar to the Octree method except that it uses a tree representation
of the refinement history instead of a geometry based octree.  The method
generates a space filling curve which is cut into <i>K</i> appropriately-sized pieces
to define contiguous parts, where the size of a piece is the sum of the
weights of the elements in that piece.  <i>K</i>, the number of parts, is not
necessarily equal to <i>P</i>, the number of processors.  It is an appropriate load balancing
method for grids that are generated by adaptive refinement when the refinement
history is available.  This implementation consists of two phases: the
construction of the refinement tree, and the definition of the parts.
<h4>
Refinement Tree Construction</h4>
The refinement tree consists of a root node and one node for each element
in the refinement history.  The children of the root node are the elements
of the initial coarse grid.  The children of all other nodes are the elements
that were formed when the parent element was refined.  Upon first invocation,
the refinement tree is initialized.  This creates the root node and initializes
a hash table that maps global IDs into nodes of the refinement tree.
It also queries the user for the elements of the initial grid and creates
the children of the root node.  Unless the user provides the order
through which to traverse the elements of the initial grid, a path is
determined through the initial elements along with the "in" vertex and
"out" vertex of each element, i.e., the vertices through which the path
passes to move from one element to the next.
This path can be determined by a Hilbert space filling curve, Sierpinski
space filling curve (triangles only), or an algorithm that attempts to make
connected parts (connectivity is guaranteed for triangles and
tetrahedra).
The refinement tree is required to have all initial coarse grid elements,
not just those that reside on the processor.  However, this requirement is not
imposed on the user; a communication step fills in the elements from other
processors.  This much of the tree persists throughout execution of the
program.  The remainder of the tree is reconstructed on each invocation of
the refinement tree partitioner.  The remainder of the tree is built through
a tree traversal.  At each node, the user is queried for the children of the
corresponding element.  If there are no children, the user is queried for
the weight of the element.  If there are children, the order of the children
is determined such that a tree traversal produces a space filling curve.
The user indicates what type of refinement was used to produce the children
(bisection of triangles, quadrasection of quadrilaterals, etc.).  For each
supported type of refinement, a template based ordering is imposed.  The
template also maintains an "in" and "out" vertex for each element
which are used by the template to determine the beginning and end of the space
filling curve through the children.  If the
refinement is not among the types supported by templates, an exhaustive
search is performed to find an appropriate order, unless the user provides
the order.
<h4>
Partition algorithm</h4>
The algorithm that determines the parts uses four traversals of the
refinement tree.  The first two traversals sum the weights in the tree.
In the first traversal, each node gets the sum of the weights of all the
descendant nodes that are assigned to this processor.  The processors then
exchange information to fill in the partial sums for the leaf elements
that are not owned by this processor.  (Note that an unowned leaf on one
processor may be the root of a large subtree on another processor.)
The second traversal completes the summation of the weights.  The root
now has the sum of all the weights, which, in conjunction with an array
of relative part sizes, determines the desired weight of each part.  
Currently the array of part sizes are all equal, but in the future
the array will be input to reflect heterogeneity in the system.  The third
traversal computes the partition by adding subtrees to a part
until the size of the part meets the desired weight, and counts
the number of elements to be exported.  Finally, the fourth traversal
constructs the export list.
<h3>
Data structures</h3>
The implementation of the refinement tree algorithm uses three data
structures which are contained in <i>reftree/reftree.h</i>.  <i>Zoltan_Reftree_data_struct</i>
is the structure pointed to by <i>zz->LB.Data_Structure</i>.  It contains a pointer
to the refinement tree root and a pointer to the hash table.
<i>Zoltan_Reftree_hash_node</i> is an entry in the hash table.  It consists of a global ID,
a pointer to a refinement tree node, and a "next" pointer from which
linked lists at each table entry are constructed to handle collisions.
<i>Zoltan_Reftree_Struct</i> is
a node of the refinement tree.  It contains the global ID, local ID,
pointers to the children, weight and summed weights, vertices of the
element, "in" and "out" vertex, a flag to indicate if this element is
assigned to this processor, and the new part number.
<h3>
Parameters</h3>
There are two parameters. <a href="../ug_html/ug_alg_reftree.html">REFTREE_HASH_SIZE</a> determines the size of
the hash table.
<a href="../ug_html/ug_alg_reftree.html">REFTREE_INITPATH</a> determines which
algorithm to use to find a path through the initial elements.
Both are set by <b>Zoltan_Reftree_Set_Param</b> in the file <i>reftree/reftree_build.c</i>.
<h3>
Main routine</h3>
The main routine is <b>Zoltan_Reftree_Part</b> in file <i>reftree/reftree_part.c</i>.
<p>
<hr WIDTH="100%">
<br>[<a href="dev.html">Table of Contents</a>&nbsp;
|&nbsp; <a href="dev_hsfc.html">Next: &nbsp; Hilbert Space-Filling Curve (HSFC)</a>
|&nbsp; <a href="dev_phg.html">Previous:&nbsp; Hypergraph Partitioning</a>&nbsp; |&nbsp; <a href="https://www.sandia.gov/general/privacy-security/index.html">Privacy and Security</a>]
</body>
</html>
